Work Request Manager API

Overview

The following information describes how to use the Work Request Manager (WRM) API:

• Subscribe for notifications
• Manage a work request end-to-end
  • Posting an event notification
  • Updating a task
    • Accept or reject a work request
    • Provide or receive additional information
    • Attach a file to a task
  • Updating an activity
    • Update a worker contact
    • Provide a status update
    • Attach a file to an activity
    • Provide outcomes
    • Close an activity
• Managing appointments and update schedules
  • Confirming an appointment
  • Determine available timeslots
  • Reschedule an appointment
  • Cancel an appointment

 

---

Subscribe for notifications

In order to receive notifications about work requests and activities, consumers (Work Requestor and Work Suppliers) must complete a one-time subscription process.

There are two parts to this process:

1. Submit a subscription request - POST /subscribers with a secret key and a webhook url that is to be used to receive notifications.
2. Validate the webhook URL endpoint - Provide a GET endpoint at the webhook url to receive a challenge querystring value that must be echoed in the GET response.

Submit a subscription request

POST /subscribers

The WRM API exposes an endpoint (POST /subscribers) to enable consumers to subscribe for outbound notifications from the WRM. The subscribing party uses the client authentication credentials supplied by Chorus for Basic Authentication.

In order to submit a subscription request, the Work Requester or Work Supplier provides Chorus with a secret key and a webhook URL where notifications are sent.

WRM generates an HMAC signature of notification payloads and includes that signature in the request headers of the content distribution request. The X-Hub-Signature header's value is in the form "sha256=". The signature is computed using the HMAC algorithm sha256 with the request body as the data and the secret key as the key.

The secret key is subsequently used to generate the X-Hub-Signature that is included in all notifications outbound from WRM to the subscriber:

[HTTP Header] X-Hub-Signature: sha256=7d3......a23791c5f6

When the subscriber receives the notification message, they use the secret key to decrypt the X-Hub-Signature to verify the request source is the WRM API.

Validate the webhook URL endpoint

GET /[webhook]

The consumer exposes a GET endpoint at the provided webhook URL to receive the challenge. This is an anonymous authentication call, and will uses the encrypted X-Hub-Signature header detailed above.

After the POST /subscribers operation has been successfully called, the internal WRM publish/subscribe subsystem performs a GET operation against the provided webhook URL with a one-time, unique challenge string.

The response to the GET operation must echo the provided challenge string in a json body with an 200 http status code to become verified.

Example

A request is sent from WRM to GET https://consumer_domain/endpoint/?challenge=unique_generated_string&subscriberId=123

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: XXX
Date: Fri, 15 Jan 2021 05:08:21 GMT
Cache-control: private
{
    "challenge": "unique_generated_string"
}

 

---

Manage a work request end-to-end

The following table describes the end-to-end process for a work request:

The following diagram shows the state transition of a work request:

 

---

Posting an event notification

POST /notifications

Use this endpoint to notify the Work Requestor of all updates and changes to a task and its associated activitites.

The following table describes the attributes required for all notification types:

Each notification type has different attributes that are required. See details below, or the /notifications method in the Specification.

 

---

Updating a task

This section describes how to use the WRM API to update a task:

• Accept or reject a work request
• Provide or receive additional information
• Attach a file to a task

Accept or reject a work request

To accept or reject a work request use the AcceptTaskEvent or the RejectTaskEvent notificationTypes.

Rules:

• A work request must be accepted before work can start.
• A work request can only be rejected if work hasn't started.
• When rejecting a Work Request the rejectReason attribute must be supplied.

The following table describes the additional attributes required for the AcceptTaskEvent or RejectTaskEvent event notifications:

Provide or receive additional information

To send additional information use the UpdateTaskAdditionalInfosEvent notificationType.

Rule: The interactionType, information, and createdBy fields are mandatory.

The table below describes the additional attributes available for the UpdateTaskAdditionalInfosEvent event notification. Multiple additional information records on a task can be added or updated:

 

Attach a file to a task

To attach or update a file use the UpdateTaskFileAttachmentsEvent notificationType.

Rules:

• When updating file attachments on a task, the entire array of file attachments to the task must be provided.
• The update task event must verify that the party requesting the update is the owner of the files.

The table below describes the additional attributes available for the UpdateTaskFileAttachmentsEvent event notification:

 

---

Updating an activity

This section describes how to use the WRM API to update a task:

• Update a worker contact
• Provide a status update
• Attach a file to an activity
• Provide outcomes
• Close an activity

For updating one or more activities on a task, the following additional attributes are required. Not all activities on a task are required to be updated in each event notification:

 

Update a worker contact

To send Chorus the details of a worker contact use the UpdateTaskActivityWorkerEvent notificationType.

Rule: Provide the worker's name either in the name attribute or both the firstName and lastName attributes.

The following table describes the additional attributes required for the UpdateTaskActivityWorkerEvent event notification. Multiple activities on a task can be updated:

Note: See Types > Contact for details on additional attributes for the Contact object.

 

Update a schedule

To send Chorus the details of an updated schedule for an activity use the UpdateTaskActivityScheduleByWorkSupplierEvent notificationType.

Rule: Send this notification after:

• confirming schedule details for an activity
• rescheduling an activity
• cancelling an appointment.

See Managing appointments and updating schedules below.

The following table describes the additional attributes required for the UpdateTaskActivityScheduleByWorkSupplierEvent event notification. Multiple activities on a task can be updated:

 

Provide a status update

To send Chorus a status update use the UpdateTaskActivityStatusEvent notificationType. See Manage a work request end-to-end above for the state types.

Rule: The geoTag attribute is mandatory when the category is Active and the state is OnSite.

The following table describes the additional attributes required for the UpdateTaskActivityStatusEvent event notification. Multiple activities on a task can be updated:

 

Attach a file to an activity

To attach or update a file use the UpdateTaskActivityFileAttachmentsEvent notificationType.

Rules:

• When updating file attachments on activities, the entire array of file attachments to the activity must be provided.
• The update task event must verify that the party requesting the update is the owner of the files.

The table below describes the additional attributes available for the UpdateTaskActivityFileAttachmentsEvent event notification. Multiple activities on a task can be updated:

 

Provide outcomes

To send Outcomes use the UpdateTaskActivityOutcomesEvent notificationType.

The table below describes the additional attributes available for the UpdateTaskActivityOutcomesEvent event notification. Multiple activities on a task can be updated:

 

Close an activity

To close an activity, use the CloseTaskActivityEvent notificationType.

When all activities on a task are closed (including verification activities), the task is automatically closed.

This table below describes the additional attributes avaiable for the CloseTaskActivityEvent event notification. Multiple activities on a task can be updated:

 

---

Managing appointments and updating schedules

This section describes how to manage appointments:

• Confirm a reserved appointment
• Reschedule an appointment
• Cancel an appointment

These operations are independent of the main work request management workflow, but the UpdateTaskActivityScheduleByWorkSupplier event notification must be posted to provide updates back to the work requestor.

When the Work Supplier creates a task or adds an activity to a task, the following information is provided in the activity schedule (not all attributes may be present):

The CreateTaskNotify and AddActivityNotify event notifications also provide an externalScheduleReference from the Work Supplier's internal system.

 

Confirm an appointment

POST /appointments/{bookingId}/confirm

Use this endpoint to confirm an existing reserved appointment.

The table below describes the attributes required to confirm a reserved appointment for all task types:

The table below describes the additional attributes required to confirm a reserved appointment for a Fulfil task:

The table below describes the additional attributes required to confirm a reserved appointment for an Assure task:

After confirming the appointment, post a notification using the UpdateTaskActivityScheduleByWorkSupplierEvent event notification to advise Chorus of the confirmed appointment. See Update a schedule above.

 

Determine available timeslots

GET /appointments/{bookingId}/timeslots

Use this endpoint to get a list of available timeslots for an appointment for rescheduling.

The following table describes the query parameters required:

 

Reschedule an appointment

PUT /appointments/{bookingId}

Use this endpoint to:

• request a change of date and time for an existing confirmed appointment
• reschedule a previously cancelled appointment.

Determine the available timeslots to reschedule the appointment using GET /appointments/{bookingId}/timeslots, see Determine available timeslots above. Work Requestors are responsible for maintaining their availability through the Service Company Alliance (SCA) system.

Rules:

• Work Suppliers are responsible for supplying the correct booking id and appointment details to the WRM, using the UpdateTaskActivityScheduleByWorkSupplierEvent notification.
• For Assure tasks, either the earliest start or latest end date and times are specified - this determines the schedule type.

Note: If all timeslots for the schedule are used, the PUT /appointments/{bookingId} operation acts as an override and allows negative units, i.e. the available units becomes -1.

The table below describes the attributes required to reschedule an appointment:

After rescheduling the appointment, post a notification using the UpdateTaskActivityScheduleByWorkSupplierEvent event notification to advise Chorus of the updated timeslot. See Update a schedule above.

 

Cancel an Appointment

DELETE /appointments/{bookingId}

Use this endpoint to cancel an appointment. This removes the appointment but allows it to be rescheduled later.

Rules:

• Work Suppliers are responsible for supplying the correct booking id to the WRM.
• Work Suppliers must retain the original booking ID to use if they want to reschedule a cancelled appointment.
• For Assure tasks, either the earliest start or latest end date and times are specified - this determines the schedule type.

Note: There are no attributes required (except for the bookingId) and no payload is returned.

After cancelling the appointment, post a notification using the UpdateTaskActivityScheduleByWorkSupplierEvent event notification to advise Chorus of the cancelled appointment. See Update a schedule above.